home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / grab.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  8.2 KB  |  290 lines
  1. '\"
  2. '\" Copyright 1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/grab.man,v 1.4 92/08/07 08:57:20 ouster Exp $ SPRITE (Berkeley)
  11. '/" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS grab cmds
  189. .BS
  190. '\" Note:  do not modify the .SH NAME line immediately below!
  191. .SH NAME
  192. grab \- Confine pointer and keyboard events to a particular window sub-tree
  193. .SH SYNOPSIS
  194. \fBgrab\fR
  195. .br
  196. \fBgrab \fIwindow\fR
  197. .br
  198. \fBgrab \fB\-global \fIwindow\fR
  199. .BE
  200.  
  201. .SH DESCRIPTION
  202. .PP
  203. This command implements simple pointer and keyboard grabs for Tk.
  204. If the \fIwindow\fR argument is specified, then the pointer and keyboard
  205. are grabbed to that window as described below.
  206. If a grab is already in effect for another window in this
  207. application then the existing grab is automatically released.
  208. If a grab is already in effect for another application then
  209. an error is returned.
  210. If the \fIwindow\fR argument is specified as an empty string
  211. or as \fBnone\fR then any existing grab in the application is
  212. released.
  213. In all of the above cases an empty string is returned.
  214. If \fBgrab\fR is invoked with no arguments then the path name of
  215. the current grab window is returned, or \fBnone\fR if no grab
  216. is active in this application.
  217. .PP
  218. Tk's grabs are somewhat different than the grabs
  219. described in the Xlib documentation.
  220. A Tk grab simply restricts all pointer events to the window tree
  221. rooted at \fIwindow\fR.
  222. Whenever the pointer is within \fIwindow\fR's subtree, the pointer
  223. will behave exactly the same as if there had been no grab at all
  224. and all events will be reported in the normal fashion.
  225. When the pointer is outside \fIwindow\fR's tree, button presses and
  226. releases and
  227. mouse motion events are reported to \fIwindow\fR, and window entry
  228. and window exit events are ignored.
  229. The grab subtree ``owns'' the pointer:
  230. windows outside the grab subtree will be visible on the screen
  231. but they will be totally insensitive until the grab is released.
  232. The tree of windows underneath \fIwindow\fR can include top-level
  233. windows.
  234. If this is the case, then all of those top-level windows
  235. and their descendants will continue to receive mouse events
  236. during the grab.
  237. .PP
  238. Two forms of grabs are possible:  local and global.
  239. A local grab affects only the grabbing application:  events will
  240. be reported to other applications as if the grab had never occurred.
  241. Grabs are local by default.
  242. A global grab is requested with the \fB\-global\fR switch.
  243. In this case the grab will lock out all applications on the screen,
  244. so that only the given subtree of the grabbing application will be
  245. sensitive to pointer events.
  246. During global grabs the window manager will not receive pointer
  247. events either.
  248. .PP
  249. During local grabs, keyboard events are handled as usual:  the window
  250. manager controls which application receives keyboard events, and
  251. if they are sent to any window in the grabbing application then they are
  252. redirected to the focus window.
  253. During a global grab Tk grabs the keyboard so that all keyboard events
  254. are always sent to the grabbing application.
  255. The \fBfocus\fR command is still used to determine which window in the
  256. application receives the keyboard events.
  257. The keyboard grab is released when the grab is released.
  258. .PP
  259. Grabs apply to particular displays.  If an application has windows
  260. on multiple displays, then it can establish a separate grab on each
  261. display.
  262. The grab on a particular display affects only the windows on
  263. that display.
  264. .PP
  265. Pointer events include mouse button presses, mouse button releases,
  266. pointer motions, window entries, and window exits.
  267. Keyboard events include key presses and key releases.
  268.  
  269. .SH BUGS
  270. .PP
  271. If \fBgrab\fR is invoked several times in a row with different
  272. \fIwindow\fR arguments and insufficient time to process all pending
  273. events between the invocations, then the grab-related events may
  274. end up in the wrong order in the event queue.  This problem is
  275. mostly likely to occur with local grabs.  The solution is to insert
  276. \fBafter\fR commands between the \fBgrab\fR invocations, so that
  277. there's enough time to clear the event queue before the next
  278. \fBgrab\fR invocation.
  279. .PP
  280. It took an incredibly complex and gross implementation to produce
  281. the simple grab effect described above.
  282. Given the current implementation, it isn't safe for applications
  283. to use the Xlib grab facilities at all except through the Tk grab
  284. procedures.
  285. If applications try to manipulate X's grab mechanisms directly,
  286. things will probably break.
  287.  
  288. .SH KEYWORDS
  289. grab, variable, wait, window
  290.